Skip to content

feat(sync): Binance USDⓈ-M futures history - #57

Merged
ChristopherDownie merged 2 commits into
mainfrom
feat/binance-futures-sync
Oct 27, 2026
Merged

ChristopherDownie merged 2 commits into
mainfrom
feat/binance-futures-sync

Conversation

@ChristopherDownie

@ChristopherDownie ChristopherDownie commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #56, which should merge first; this PR's base then moves to main.

Syncs Binance USDⓈ-M futures into the journal, using broker-sdk 0.6.0 (#30).

Cause

broker-sdk's Binance adapter returned no fills, so a Binance account's dashboard, calendar and reports stayed empty. broker-sdk 0.6.0 reads USDⓈ-M futures fills (LuxAlgo/broker-sdk#25), as #30 asked for. Once those fills arrive, the journal side has two problems:

  • Hedge mode. Binance can hold a long and a short on the same symbol at once. Synced fills net by symbol, so covering the short would close part of the long, and both trades would come out wrong.
  • History limit. Binance futures history only goes back three months. Selling a long opened before that would show up as a short that never existed.

Fix

  • Hedge mode. A fill with broker-sdk's Trade.positionSide is journaled in a group for its side, sync-hedge:long or sync-hedge:short. The round-trip engine keeps groups apart, as it does for separately reported positions in imports. Sync rows may now carry import metadata to hold the group. One-way fills are unchanged.
  • History limit. This uses keepWithinHistory from fix(sync): Webull trade history without phantom positions #56, which replays each group on its own and keeps only the part of a close that the history covers.
    • Binance's futures position list checks unlabeled futures fills, as Webull's does for equities.
    • Hedge-mode positions are left out of that check, since their sides replay in their own groups.
  • Quarterly contracts. A Binance quarterly contract (BTCUSDT_261225) settles at delivery without a fill, so the position list can't say whether its history is complete. Its fills are kept, and one held to delivery stays open. The docs say so.
  • Docs. README and changelog.

Test

apps/web/tests/binance-sync.test.ts runs syncAccount with broker-sdk's Binance adapter against a stubbed Binance:

  • Futures fills become futures trades with their USDT and BNB fees, and a re-sync adds nothing.
  • In hedge mode, a long and a short held at once stay two trades.
  • Closes of positions opened before the history are skipped, in one-way and hedge mode.
  • A position partly opened before the history keeps the covered part of its close, in both modes, and a re-sync leaves it alone.
  • An open hedge short doesn't cover for a one-way close from before the history.
  • A quarterly contract held to delivery keeps its opening fill.
  • A later sync asks Binance only for recent fills.

The hedge, history-limit and delivery tests each fail without their part of the fix.

Checks run locally

All of these pass:

  • pnpm format:check
  • pnpm typecheck
  • pnpm test (71 files, 665 tests)
  • node scripts/check-licenses.mjs
  • pnpm -r --filter "./packages/*" build
  • pnpm build

Fixes #30

broker-sdk 0.6.0 returns Binance USDⓈ-M futures fills (three months of
history) and marks hedge-mode fills and positions with their side.

- A hedge-mode fill is journaled in its side's group (sync-hedge:long or
  sync-hedge:short). A long and a short held at once on one symbol then
  stay two trades instead of netting. Sync rows may now carry import
  metadata for this.
- Binance's futures position list vouches for unlabeled futures fills,
  as Webull's does for equities. A close of a position opened before
  the three months is skipped, or kept for the part the history covers.
  Hedge-mode positions stay out of that check, since their sides replay
  in their own groups.
- A Binance quarterly contract settles at delivery without a fill, so
  its flat position can't show its history is incomplete. Its fills are
  kept, and one held to delivery stays open.
@ChristopherDownie
ChristopherDownie marked this pull request as ready for review October 27, 2026 00:48
@ChristopherDownie
ChristopherDownie changed the base branch from fix/webull-sync to main October 27, 2026 00:49
@ChristopherDownie
ChristopherDownie merged commit 834e7b6 into main Oct 27, 2026
1 check passed
@ChristopherDownie
ChristopherDownie deleted the feat/binance-futures-sync branch October 28, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature / Bug] Binance integration lacks Futures support and returns empty trades array

1 participant